home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / IOIterator.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  4KB  |  143 lines
  1. /*
  2.      File:        IOIterator.h
  3.  
  4.      Contains:    xxx put contents here xxx
  5.  
  6.      Version:    Technology:    xxx put the technology version here xxx
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __IOITERATOR__
  19. #define __IOITERATOR__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24.  
  25. #ifdef __cplusplus
  26. extern "C" {
  27. #endif
  28.  
  29. #if PRAGMA_IMPORT_SUPPORTED
  30. #pragma import on
  31. #endif
  32.  
  33. #if PRAGMA_ALIGN_SUPPORTED
  34. #pragma options align=mac68k
  35. #endif
  36.  
  37. #if FOR_SYSTEM8_PREEMPTIVE
  38. /* typedefs*/
  39. typedef UInt32 IteratorDescVersion;
  40. /*
  41. ###########################################################
  42.  How to use the IteratorDescVersion
  43. ###########################################################
  44.  Each family will define a k<Family>CurrentIteratorDescVersion constant
  45.  in its *.i file. The client will check the returned IteratorDescVersion
  46.     value against this constant to make sure there's no version mismatch 
  47.      problem.
  48.  Common data structure used by all I/O family iterators
  49. */
  50. struct IODeviceRef {
  51.     UInt32                             contents[4];
  52. };
  53. typedef struct IODeviceRef IODeviceRef;
  54.  
  55. /*
  56.  a family unique reference number for returned devices.
  57.  this is an opaque field, for now, use the name registry Ref value of the             
  58.     device in question.    
  59.  The IODeviceRef is unique within a family, NOT unique across the entire I/O name space
  60. */
  61. struct IOCommonInfo {
  62.     IODeviceRef                     ref;
  63.     IteratorDescVersion             versionNumber;
  64. };
  65. typedef struct IOCommonInfo IOCommonInfo;
  66.  
  67. /* IteratorDescVersion versionNumber: version number of the family specific IOIteratorData*/
  68. #endif
  69. /*
  70. ###########################################################
  71.  How to copy name registry ref --> IODeviceRef
  72. ###########################################################
  73. {
  74.     IOCommonInfo            DeviceData;
  75.     RegEntryRef                *anotherReg, *whichDevice;
  76.     anotherReg = (RegEntryRef *)&DeviceData;
  77.     *anotherReg = *whichDevice;
  78. }
  79. ###########################################################
  80.  How to define a family specific IOIteratorData structure
  81. ###########################################################
  82.  struct <FamilyName>IOIteratorData
  83.  {
  84.       IOCommonInfo     IOCI;    
  85.                     // common data for all families    
  86.         f1,            // Individual family specific data
  87.         f2,
  88.         etc...
  89.  };
  90.  Example 1: (A possible implementation for the SCSI iterator)
  91.     struct SCSIIOIteratorData
  92.  {
  93.       IOCommonInfo     IOCI;    
  94.                     // common data for all families    
  95.         UInt32            BusID;
  96.         UInt32            TargetID;
  97.         UInt32            LUN;
  98.  };
  99. ###########################################################
  100.  How to define a family specific iterator function
  101. ###########################################################
  102. OSStatus <FamilyName><IterationSpecification>GetDeviceData 
  103.             (    ItemCount             requestItemCount,
  104.                 FamilyIteratorData     *(&<FamilyName>IOIteratorDataArray[requestItemCount]),                              
  105.                 ItemCount             *totalItemCountPtr );
  106.                 
  107.  For returning ALL devices that the family have access to
  108.  OSStatus <FamilyName><IterationSpecification>GetDeviceData 
  109.             (    UInt32                familySpecificParam,
  110.                 ItemCount             requestItemCount,
  111.                 FamilyIteratorData     *(&<FamilyName>IOIteratorDataArray[requestItemCount]),
  112.                 ItemCount             *totalItemCountPtr );
  113.                 
  114.  For returning a subset of devices, filtered by some family specific parameters
  115.  EXAMPLES:
  116.  OSStatus SCSIGetDeviceData 
  117.             (    ItemCount             requestItemCount,
  118.                 ItemCount             *totalItemCountPtr,
  119.                 SCSIIteratorData     *(&SCSIIOIteratorDataArray[requestItemCount]));
  120.  To get all scsi devices
  121.  OSStatus SCSIBusGetDeviceData 
  122.             (    UInt32                BusID,
  123.                 ItemCount             requestItemCount,
  124.                 ItemCount             *totalItemCountPtr,
  125.                 SCSIIteratorData     *(&SCSIIOIteratorDataArray[requestItemCount]));
  126.  To get all scsi devices that matches the input BusID
  127. */
  128.  
  129. #if PRAGMA_ALIGN_SUPPORTED
  130. #pragma options align=reset
  131. #endif
  132.  
  133. #if PRAGMA_IMPORT_SUPPORTED
  134. #pragma import off
  135. #endif
  136.  
  137. #ifdef __cplusplus
  138. }
  139. #endif
  140.  
  141. #endif /* __IOITERATOR__ */
  142.  
  143.